home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1995 August: Tool Chest / Dev.CD Aug 95 TC / Dev.CD Aug 95 TC.toast / Tool Chest / Interfaces / UniversalInterfaces 2.0 / PInterfaces / Translation.p < prev    next >
Encoding:
Text File  |  1995-04-18  |  11.7 KB  |  319 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        Translation.p
  3.  
  4.      Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5.  
  6.      Version:    Technology:    Macintosh Easy Open 1.1
  7.                  Package:    Universal Interfaces 2.0 in “MPW Latest” on ETO #17
  8.  
  9.      Copyright:    © 1984-1995 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17.  
  18. }
  19.  
  20. {$IFC UNDEFINED UsingIncludes}
  21. {$SETC UsingIncludes := 0}
  22. {$ENDC}
  23.  
  24. {$IFC NOT UsingIncludes}
  25.  UNIT Translation;
  26.  INTERFACE
  27. {$ENDC}
  28.  
  29. {$IFC UNDEFINED __TRANSLATION__}
  30. {$SETC __TRANSLATION__ := 1}
  31.  
  32. {$I+}
  33. {$SETC TranslationIncludes := UsingIncludes}
  34. {$SETC UsingIncludes := 1}
  35.  
  36.  
  37. {$IFC UNDEFINED __TYPES__}
  38. {$I Types.p}
  39. {$ENDC}
  40. {    ConditionalMacros.p                                            }
  41.  
  42. {$IFC UNDEFINED __FILES__}
  43. {$I Files.p}
  44. {$ENDC}
  45. {    MixedMode.p                                                    }
  46. {    OSUtils.p                                                    }
  47. {        Memory.p                                                }
  48.  
  49. {$IFC UNDEFINED __COMPONENTS__}
  50. {$I Components.p}
  51. {$ENDC}
  52.  
  53. {$IFC UNDEFINED __TRANSLATIONEXTENSIONS__}
  54. {$I TranslationExtensions.p}
  55. {$ENDC}
  56. {    Quickdraw.p                                                    }
  57. {        QuickdrawText.p                                            }
  58.  
  59. {$PUSH}
  60. {$ALIGN MAC68K}
  61. {$LibExport+}
  62.     
  63. TYPE
  64.     DocOpenMethod = INTEGER;
  65.  
  66.  
  67. CONST
  68.     domCannot                    = 0;
  69.     domNative                    = 1;
  70.     domTranslateFirst            = 2;
  71.     domWildcard                    = 3;
  72.  
  73. { 0L terminated array of OSTypes, or FileTypes}
  74.     
  75. TYPE
  76.     TypesBlock = ARRAY [0..63] OF OSType;
  77.  
  78.     TypesBlockPtr = ^OSType;
  79.  
  80. { Progress dialog resource ID}
  81.  
  82. CONST
  83.     kTranslationScrapProgressDialogID = -16555;
  84.  
  85. { block of data that describes how to translate}
  86.  
  87. TYPE
  88.     FileTranslationSpec = RECORD
  89.         componentSignature:        OSType;
  90.         translationSystemInfo:    Ptr;
  91.         src:                    FileTypeSpec;
  92.         dst:                    FileTypeSpec;
  93.     END;
  94.  
  95.     FileTranslationSpecArrayPtr = ^FileTranslationSpec;
  96.  
  97. {****************************************************************************************
  98. * 
  99. *   GetFileTypesThatAppCanNativelyOpen
  100. * 
  101. *  This routine returns a list of all FileTypes that an application can open by itself
  102. * 
  103. *  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  104. *             appSignature        signature (creator) of application
  105. *             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  106. * 
  107. *  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  108. }
  109.  
  110. FUNCTION GetFileTypesThatAppCanNativelyOpen(appVRefNumHint: INTEGER; appSignature: OSType; VAR nativeTypes: FileType): OSErr;
  111.     {$IFC NOT GENERATINGCFM}
  112.     INLINE $701C, $ABFC;
  113.     {$ENDC}
  114. {****************************************************************************************
  115. * 
  116. *  ExtendFileTypeList
  117. * 
  118. *  This routine makes a new list of file types that can be translated into a type in the given list
  119. *  Used by StandardFile
  120. * 
  121. *  Enter:    originalTypeList        pointer to list of file types that can be opened
  122. *             numberOriginalTypes        number of file types in orgTypeList
  123. *              extendedTypeList        pointer to a buffer to be filled with file types
  124. *             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  125. * 
  126. *  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  127. *             numberExtendedTypes        number of file types put in extendedTypeList
  128. }
  129. FUNCTION ExtendFileTypeList({CONST}VAR originalTypeList: FileType; numberOriginalTypes: INTEGER; VAR extendedTypeList: FileType; VAR numberExtendedTypes: INTEGER): OSErr;
  130.     {$IFC NOT GENERATINGCFM}
  131.     INLINE $7009, $ABFC;
  132.     {$ENDC}
  133. {****************************************************************************************
  134. * 
  135. * 
  136. *  This routine checks if a file can be opened by a particular application.
  137. *  If so, it returns if it needs to be translated first, and if so then how.
  138. *  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  139. *  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  140. * 
  141. *  Enter:    targetDocument        document to check if it can be opened
  142. *             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  143. *             appSignature        signature (creator) of application to open doc
  144. *             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  145. *             onlyNative            whether to consider if document can be translated before opening
  146. *             howToOpen            pointer to buffer in which to put how the document can be opened
  147. *             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  148. * 
  149. *  Exit:    howToOpen            whether file needs to be translated to be read
  150. *             howToTranslate        if file can be translated, buffer filled in with how to translate
  151. *             returns                noErr, noPrefAppErr
  152. }
  153. FUNCTION CanDocBeOpened({CONST}VAR targetDocument: FSSpec; appVRefNumHint: INTEGER; appSignature: OSType; {CONST}VAR nativeTypes: FileType; onlyNative: BOOLEAN; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  154.     {$IFC NOT GENERATINGCFM}
  155.     INLINE $701E, $ABFC;
  156.     {$ENDC}
  157. {****************************************************************************************
  158. * 
  159. *  GetFileTranslationPaths
  160. * 
  161. *  This routine returns a list of all ways a translation can occure to or from a FileType.
  162. *  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  163. * 
  164. *  Enter:    srcDoc            source file or NULL for all matches
  165. *             dstDoc            destination FileType or NULL for all matches
  166. *             maxResultCount
  167. *             resultBuffer
  168. *  Exit:    number of paths
  169. }
  170. FUNCTION GetFileTranslationPaths(VAR srcDocument: FSSpec; dstDocType: FileType; maxResultCount: INTEGER; resultBuffer: FileTranslationSpecArrayPtr): INTEGER;
  171.     {$IFC NOT GENERATINGCFM}
  172.     INLINE $7038, $ABFC;
  173.     {$ENDC}
  174. {****************************************************************************************
  175. * 
  176. *  GetPathFromTranslationDialog
  177. * 
  178. *  This routine, with a given document, application, and a passed typelist will display the
  179. *  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  180. *  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  181. *  The routine returns the translation path information.
  182. * 
  183. *  Enter:    theDocument            FSSpec to document to open
  184. *             theApplication        FSSpec to application to open document
  185. *             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  186. *                                 you would like the documented translated to.  Order most perferred
  187. *                                 to least.
  188. * 
  189. *  Exit:    howToOpen            Translation method needed to open document
  190. *             howToTranslate        Translation specification
  191. *             returns                Any errors that might occur.
  192. }
  193. FUNCTION GetPathFromTranslationDialog({CONST}VAR theDocument: FSSpec; {CONST}VAR theApplication: FSSpec; typeList: TypesBlockPtr; VAR howToOpen: DocOpenMethod; VAR howToTranslate: FileTranslationSpec): OSErr;
  194.     {$IFC NOT GENERATINGCFM}
  195.     INLINE $7037, $ABFC;
  196.     {$ENDC}
  197. {****************************************************************************************
  198. * 
  199. *   TranslateFile
  200. * 
  201. *  This routine reads a file of one format and writes it to another file in another format. 
  202. *  The information on how to translated is generated by the routine CanDocBeOpened.
  203. *  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  204. *  The destination file must not exist.  It is created by this routine.  
  205. * 
  206. *  Enter:    sourceDocument            input file to translate
  207. *             destinationDocument        output file of translation
  208. *             howToTranslate            pointer to info on how to translate
  209. *  Exit:    returns                    noErr, badTranslationSpecErr 
  210. }
  211. FUNCTION TranslateFile({CONST}VAR sourceDocument: FSSpec; {CONST}VAR destinationDocument: FSSpec; {CONST}VAR howToTranslate: FileTranslationSpec): OSErr;
  212.     {$IFC NOT GENERATINGCFM}
  213.     INLINE $700C, $ABFC;
  214.     {$ENDC}
  215. {****************************************************************************************
  216. * 
  217. *   GetDocumentKindString
  218. * 
  219. *  This routine returns the string the Finder should show for the "kind" of a document
  220. *  in the GetInfo window and in the kind column of a list view.  
  221. * 
  222. *  Enter:    docVRefNum        The volume containing the document
  223. *             docType            The catInfo.fdType of the document
  224. *             docCreator        The catInfo.fdCreator of the document
  225. *             kindString        pointer to where to return the string
  226. * 
  227. *  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  228. *             returns            noErr, or afpItemNoFound if kind could not be determined
  229. }
  230. FUNCTION GetDocumentKindString(docVRefNum: INTEGER; docType: OSType; docCreator: OSType; VAR kindString: Str63): OSErr;
  231.     {$IFC NOT GENERATINGCFM}
  232.     INLINE $7016, $ABFC;
  233.     {$ENDC}
  234. {****************************************************************************************
  235. * 
  236. *  GetTranslationExtensionName
  237. * 
  238. *  This routine returns the translation system name from a specified TranslationSpec
  239. * 
  240. *  Enter:    translationMethod    The translation path to get the translation name from
  241. * 
  242. *  Exit:    extensionName        The name of the translation system
  243. *             returns                Any errors that might occur
  244. }
  245. FUNCTION GetTranslationExtensionName({CONST}VAR translationMethod: FileTranslationSpec; VAR extensionName: Str31): OSErr;
  246.     {$IFC NOT GENERATINGCFM}
  247.     INLINE $7036, $ABFC;
  248.     {$ENDC}
  249. {****************************************************************************************
  250. * 
  251. *  GetScrapDataProcPtr
  252. * 
  253. *  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  254. *  get the data to be translated.  The first call TranslateScrap will make to this is to
  255. *  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  256. *  with a list all the formats that you have available to be translated, and the length of each.
  257. *  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  258. *  the formats that 'fmts' list said was available.
  259. * 
  260. *  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  261. *             dataH                    Handle in which to put the requested data
  262. *             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  263. *             
  264. *  Exit:    dataH                    Handle is resized and filled with data in requested format
  265. }
  266. TYPE
  267.     GetScrapDataProcPtr = ProcPtr;  { FUNCTION GetScrapData(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr): OSErr; }
  268.     GetScrapDataUPP = UniversalProcPtr;
  269.  
  270. CONST
  271.     uppGetScrapDataProcInfo = $00000FE0; { FUNCTION (4 byte param, 4 byte param, 4 byte param): 2 byte result; }
  272.  
  273. FUNCTION NewGetScrapDataProc(userRoutine: GetScrapDataProcPtr): GetScrapDataUPP;
  274.     {$IFC NOT GENERATINGCFM }
  275.     INLINE $2E9F;
  276.     {$ENDC}
  277.  
  278. FUNCTION CallGetScrapDataProc(requestedFormat: ScrapType; dataH: Handle; srcDataGetterRefCon: UNIV Ptr; userRoutine: GetScrapDataUPP): OSErr;
  279.     {$IFC NOT GENERATINGCFM}
  280.     INLINE $205F, $4E90;
  281.     {$ENDC}
  282.     
  283. TYPE
  284.     GetScrapData = GetScrapDataUPP;
  285.  
  286. {****************************************************************************************
  287. * 
  288. *  TranslateScrap
  289. * 
  290. *  This routine resizes the destination handle and fills it with data of the requested format.
  291. *  The data is generated by translated one or more source formats of data supplied by
  292. *  the procedure srcDataGetter.  
  293. *  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  294. *  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  295. * 
  296. *  Enter:    sourceDataGetter            Pointer to routine that can get src data
  297. *             sourceDataGetterRefCon        Extra parameter for dataGetter
  298. *             destinationFormat            Format of data desired
  299. *             destinationData                Handle in which to store translated data
  300. *             
  301. *  Exit:    dstData                        Handle is resized and filled with data in requested format
  302. }
  303.  
  304. FUNCTION TranslateScrap(sourceDataGetter: GetScrapData; sourceDataGetterRefCon: UNIV Ptr; destinationFormat: ScrapType; destinationData: Handle; progressDialogID: INTEGER): OSErr;
  305.     {$IFC NOT GENERATINGCFM}
  306.     INLINE $700E, $ABFC;
  307.     {$ENDC}
  308.  
  309. {$ALIGN RESET}
  310. {$POP}
  311.  
  312. {$SETC UsingIncludes := TranslationIncludes}
  313.  
  314. {$ENDC} {__TRANSLATION__}
  315.  
  316. {$IFC NOT UsingIncludes}
  317.  END.
  318. {$ENDC}
  319.